Repository Management with Nexus

The following changes were made in 3.0.1:

The following changes were made in 3.0:

The following people helped improve the quality of Edition 3.0 by reporting typos, making suggestions, or contributing directly to the development of this book:

Nexus manages software “artifacts” required for development, deployment, and provisioning. If you develop software, Nexus can help you share those artifacts with other developers and end-users. Maven’s central repository has always served as a great convenience for users of Maven, but it has always been recommended to maintain your own repositories to ensure stability within your organization. Nexus greatly simplifies the maintenance of your own internal repositories and access to external repositories. With Nexus you can completely control access to, and deployment of, every artifact in your organization from a single location.

Nexus Open Source provides you with an essential level of control over the external Maven repositories you use and the internal repositories you create. It provides infrastructure and services for organizations that use repository managers to obtain and deliver software. If you create software libraries or applications for your end-users, you can use Nexus Open Source to distribute your software. If your software depends upon open source software components, you can cache software artifacts from remote repositories.

Nexus Professional was designed to meet the needs of the enterprise. It is a central point of access to external repositories which provides the necessary controls to make sure that only approved artifacts enter into your software development environment. It is also a central distribution point with the intelligence required to support the decision that go into making quality software. The extensibility provided by the custom metadata plugin coupled with REST services only available in Nexus Professional also lay the foundation for highly complex interactions within the enterprise. Once you start to use the workflow and decision support features of Nexus Professional, you will start to see it as the “assembly line” - the central collaboration point for your software development efforts.

If you are wondering which edition is appropriate for your organization. The following sections outline some reasons for choosing either Nexus Open Source of Nexus Professional.

Proximity in December 2005 as he was trying to find a way to isolate his own systems from an incredibly slow ADSL connection provided by a Hungarian ISP. Proximity started as a simple web application to proxy artifacts for a small organization with connectivity issues. Creating a local on-demand cache for Maven artifacts from the Maven Central repository gave an organization access to the artifacts on the Maven Central Repository, but it also made sure that these artifacts weren’t downloaded over a very slow ADSL connection used by a number of developers. In 2007,

Sonatype asked Tamas to help create a similar product named Nexus. Nexus is currently considered the logical next step to Proximity. Nexus currently has an active development team, and portions of the indexing code from Nexus are also being used in m2eclipse.

Repository managers serve two purposes: they act as highly configurable proxies between your organization and the public Maven repositories and they also provide an organization with a deployment destination for its own generated artifacts. Just as Source Code Management (SCM) tools are designed to manage source artifacts, Repository Managers have been designed to manage and track external dependencies and artifacts generated by your build. They are an essential part of any enterprise or open-source software development effort, and they enable greater collaboration between developers and wider distribution of software.

Maven developers are familiar with the concept of a repository: a collection of binary software artifacts and metadata stored in a defined directory structure which is used by clients such as Apache Ivy to retrieve binaries during a build process. In the case of the Maven repository, the primary type of binary artifact is a JAR file containing Java bytecode, but there is no limit to what type of artifact can be stored in a Maven repository. For example, one could just as easily deploy documentation archives, source archives, Flash libraries and applications, or Ruby libraries to a Maven repository. A Maven repository provides a platform for the storage, retrieval, and management of binary software artifacts and metadata.

In Maven, every software artifact is described by an XML document called a Project Object Model (POM). This POM contains information that describes a project and lists a project’s dependencies - the binary software artifacts which a given component depends upon for successful compilation or execution.

When Maven downloads a dependency from a repository, it also downloads that dependency’s POM. Given a dependency’s POM, Maven can then download any other libraries which are required by that dependency. The ability to automatically calculate a project’s dependencies and transitive dependencies is made possible by the standard and structure set by the Maven repository.

Maven and other tools such as Ivy which interact with a repository to search for binary software artifacts, model the projects they manage, and retrieve software artifacts on-demand from a repository. When you download and install Maven without any customization, Maven will retrieve artifacts from a Maven Central repository which serves millions of Maven users every single day. While you can configure Maven to retrieve binary software artifacts from a collection of mirrors, the best-practice is to install Nexus and use it to proxy and cache the contents of Central on your own network. <indexterm>

In addition to Central, there are a number of major organizations such as Redhat, Sun Microsystems, and Codehaus which maintain separate repositories.

While this might seem like a simple, obvious mechanism for distributing artifacts, the Java platform existed for several years before the Maven project created a formal attempt at the first repository for Java artifacts. Until the advent of the Maven repository in 2002, a project’s dependencies were gathered in a manual, ad-hoc process and were often distributed with a project’s source code. As applications grew more and more complex, and as software teams developed a need for more complex dependency management capabilities for larger enterprise applications, Maven’s ability to automatically retrieve dependencies and model dependencies between components became an essential part of software development.

If you use Maven, you are using a repository to retrieve artifacts and Maven plugins. In fact, Maven used a Maven repository to retrieve core plugins that implement the bulk of the features used in your builds. Once you start to rely on repositories, you realize how easy it is to add a dependency on an open source software library available in the Maven Central repository, and you might start to wonder how you can provide a similar level of convenience for your own developers. When you install a repository manager, you are bringing the power of a repository like Central into your organization, you can use it to proxy Central, and host your own repositories for internal and external use. In this section, we discuss the core functionality which defines what a repository manager does.

Put simply, a repository manager provides two core features:

In addition to these two core features, a repository manager also allows you to manage binary software artifacts through the software development lifecycle, search and catalog software artifacts, audit development and release transactions, and integrate with external security systems such as LDAP. The following sections define the feature sets of Nexus Open Source and Nexus Professional.

Here are a few reasons why using a repository manager is an imperative. While most people wouldn’t even think of developing software without the use of a source code control system like Subversion or Perforce, the concept of using a repository manager is still something that needs development. There are many who use Maven for years without realizing the benefits of using a repository manager. This section was written as an attempt to capture some of the benefits of using a repository manager.

This section talks about the stages of moving to a repository manager. Adopting a repository manager is not an all or nothing proposition, and there are various levels (or stages) of adoption that can be distinguished when approaching repository management. On one end of the adoption spectrum is the organization that installs a repository manager just to control and consolidate access to a set of remote repositories. On the other end of the spectrum is the organization which has integrated the repository manager into an efficient software development lifecycle, using it to facilitate decision points in the lifecycle, encouraging more efficient collaboration throughout the enterprise, and keeping detailed records to increase visibility into the software development process.

There are two distributions of Nexus: Nexus Open Source and Nexus Professional. Nexus Open Source is a fully-featured repository manager which can be freely used, customized, and distributed under the GNU Affero General Public License (AGPL) Version 3. Nexus Professional is a distribution of Nexus with features that are relevant to large enterprises and organizations which require complex procurement and staging workflows in addition to more advanced LDAP integration, Atlassian Crowd support, and other development infrastructure. The differences between Nexus Open Source and Nexus Professional are explored in the previous chapter.

The following sections detail the installation process for both Nexus Open Source and Nexus Professional.

Since Nexus separates its configuration and data storage from the application, it is easy to upgrade an existing Nexus installation. To upgrade Nexus, unpack the Nexus archive in the directory which contains the existing Nexus installation. Once the archive is unpacked, the new Nexus application directory should be a sibling to your existing sonatype-work/ directory. If you have defined a symbolic link for the version of Nexus to use, change that to point at the new Nexus application directory. When you start the new instance of Nexus it will read the existing repository configuration from the sonatype-work/

When you start Nexus, you are starting a web server on the default port of 0.0.0.0:8081. Nexus runs within a servlet container called Jetty and it is started with a native service wrapper called the Tanuki Java Service Wrapper. This service wrapper can be configured to run Nexus as a Windows service or a Unix daemon. To start Nexus, you will need to find the appropriate startup script for your platform. To see the list of available platforms, list the contents of the

The following example listing starts Nexus using the script for Mac you the available platforms, then we make the contents of the bin directory executable with chmod. The Mac OS X wrapper is started with a call to nexus start, and then we tail the wrapper.log in stating what IP address and port it is listening on.

At this point, Nexus will be running and listening on all IP addresses (0.0.0.0) that are configured for the current host on port 8081. To use Nexus, fire up a web browser and type in the URL: http://localhost:8081/nexus

While we use "localhost" throughout this book, you may need to use the IP Loopback Address of "127.0.0.1" or the IP address assigned to the machine running Nexus. Click on the "Log In" link in the upper right-hand corner of the web page, and you should see the login dialog. THE DEFAULT NEXUS USERNAME AND PASSWORD IS "admin" AND "admin123".

Nexus ships with some default passwords and settings for repository indexing that need to be changed for your installation to be useful (and secure). After installing and running Nexus, you need to make sure that you complete the following tasks:

This will trigger Nexus to re-index these repositories, during which the remote index files will be downloaded. It might take Nexus a few minutes to download the entire index, but once you have it, you’ll be able to search the entire contents of the Maven repository.

Once you’ve enabled remote index downloads, you still won’t be able to browse the complete contents of a remote repository. Downloading the remote index allows you to search for artifacts in a repository, but until you download those artifacts from the remote repository they will not show in the repository tree when you are browsing a repository. When browsing a repository, you will only be shown artifacts which have been downloaded from the remote repository.

When installing Nexus, you will often want to configure Nexus as a service. If you are on Windows, the Nexus distribution includes binaries that can work with the Windows Services subsystem and if you are on another platform such as GNU/Linux Nexus also includes scripts that can be configured to start Nexus as a service. The following sections provide instructions for configuring Nexus as a service.

If you installed Nexus as a stand-alone application, Nexus is running on a high-performance servlet container based on Java NIO. From a performance perspective, there is no reason for you not to run Nexus by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate multiple disparate applications using tools like mod_rewrite. For this reason, we’ve included some brief instructions for configuration Apache httpd. We assume that you’ve already installed Apache 2, and that you are using a Virtual Host for www.somecompany.com.

Let’s assume that you wanted to host Nexus behind Apache HTTPd at the URL http://www.somecompany.com. To do this, you’ll need to change the context path that Nexus is served from.

At this point, edit the HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Nexus via mod_proxy at http://www.somecompany.com/

If you just wanted to continue to serve Nexus at the /nexus context path, you would not change the contextPath in in your ProxyPass and ProxyPassReverse

Apache configuration is going to vary based on your own application’s requirements and the way you intend to expose Nexus to the outside world. If you need more details about Apache httpd and mod_proxy, please see http://httpd.apache.org

The Nexus Open Source WAR has been successfully tested in Tomcat, Jetty, and Resin. If you need to run Nexus under Glassfish, please see <xref linkend="install-sect-war-gf" />. To download the Nexus Open Source WAR, go to http://nexus.sonatype.org/using/download.html. Click on the Download Site link and then download the Nexus WAR. Once you have downloaded the Nexus Open Source WAR, you can install it in a servlet container or application server.

The process for installing a WAR in an servlet container or application server is going to vary for each specific application. Often, this installation process is as simple as dropping a WAR file in a special directory and restarting the container. For example, to install the Nexus WAR in Tomcat, drop the your Tomcat instance. Assuming that Tomcat is configured on port 8080 once Tomcat is started, Nexus will be available on http://localhost:8080/nexus-webapp-1.6.0.

If you would like a less verbose URL, copy nexus-webapp-1.6.0.war to a file named nexus.war before copying the distribution to

To install a Nexus Professional license, click on Licensing in the Enterprise menu. Clicking on Licensing will bring up the panel shown in <xref linkend="fig-installations-licensing" />. To upload your Nexus Professional license, click on Browse…, select the file, and click on Upload.

Once you have selected a license and uploaded it to Nexus, Nexus Professional will display a dialog box with the Nexus Professional End-user License Agreement as shown in <xref linkend="fig-installation-eula" />. If you agree with the terms and conditions, click on "I Agree".

Once you have agreed to the terms and conditions contained in the End User License Agreement, Nexus Professional will then display a dialog box confirming the installation of a Nexus Professional license as shown in <xref linkend="fig-installation-license-upload-config" />.

If you need to move your Nexus Professional license, you can click on the "Uninstall License" button at the bottom of the Licensing Panel. Clicking on this button will show the dialog in <xref linkend="fig-installation-config-uninstall" /> which confirms that you want to uninstall a license.

Clicking Yes in this dialog box will uninstall the license from Nexus Professional and display another dialog which confirms that the license has been successfully uninstalled.

The following sections describe the various directories that are a part of any Nexus installation. When you install Nexus Open Source or Nexus Professional, you are creating two directories: a directory which contains the Nexus runtime and application, and a directory which contains your own configuration and data. When you upgrade to a newer version of Nexus, you replace the Nexus application directory and retain all of your own custom configuration and repository data in sonatype-work/

To use Nexus, you will configure Maven to check Nexus instead of the public repositories. To do this, you’ll need to edit your mirror settings in your <filename>~/.m2/settings.xml file. First, we’re going to demonstrate how to configure Maven to consult your Nexus installation instead of retrieving artifacts directly from the Maven Central repository. After we override the central repository and demonstrate that Nexus is working, we’ll circle back to provide a more sensible set of settings that will cover both releases and snapshots.

If you are adopting Nexus for internal development you should configure a single Nexus group which contains both releases and snapshots. To do this, add snapshot repositories to your public group, and add the following mirror configuration to your Maven settings in ~/.m2/settings.xml

In <xref linkend="ex-maven-nexus-simple" /> we have defined a single profile: nexus profile is configured to download from the central repository with a bogus URL. This URL is overridden by the mirror setting in the same settings.xml file to point to the URL of your single Nexus group. The nexus group is then listed as an active profile in the <sgmltag>activeProfiles element.

If you’ve configured your Maven settings.xml to list the Nexus public group as a mirror for all repositories, you might encounter projects which are unable to retrieve artifacts from your local Nexus installation. This usually happens because you are trying to build a project which has defined a custom set of repositories and snapshotRepositories in a pom.xml. When you encounter a project which contains a custom repository element in a pom.xml add this repository to Nexus as a new proxy repository and then add the new proxy repository to the public group.

To add a repository, log into Nexus as an Administrator, and click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Clicking on this link should bring up a window that lists all of the repositories which Nexus knows about. You’ll then want to create a new proxy repository. To do this, click on the Add link that is directly above the list of repositories. When you click the Add button, click the down arrow directly to the right of the word Add, this will show a drop-down which has the options: Hosted Repository, Proxy Repository, Virtual Repository, and Repository Group. Since you are creating a proxy repository, click on Proxy Repository.

Once you do this, you will see a screen resembling <xref linkend="fig-add-repo" />. Populate the required fields Repository ID and the Repository Name with "caja" and "Google Caja". Set the Repository Policy to "Release", and the Remote Storage Location to http://google-caja.googlecode.com/svn/maven

Once you’ve filled out this screen, click on the Save button. Nexus will then be configured with the caja proxy repository. Do the same thing for the oauth repository. Create a repository with the Repository ID of oauth, with a Release policy, and the Remote Storage Location of http://oauth.googlecode.com/svn/code/maven

Next you will need to add both of these new repositories to the public Nexus Group. To do this, click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Nexus lists Groups and Repositories in the same list so click on the public group. After clicking on the public group, you should see the Browse and Configuration tabs in the lower half of the Nexus window.

Clicking on the Configuration tab will bring up a screen which looks like <xref linkend="fig-add-to-group" />.

To add the two new repositories to the public Nexus Group, find the repositories in the Available Repositories list on the right, click on the repository you want to add and drag it to the left to the Ordered Group Repositories list. Once the repository is in the Ordered Group Repositories list you can click and drag the repository within that list to alter the order in which a repository will be searched for a matching artifact. Once the Google Caja and Google OAuth project repositories are added to the public Nexus Group, you should be able to build Apache Shindig and watch Maven download the Caja and OAuth artifacts from the respective repositories.

In the last few sections, you encountered a situation where you needed to add two custom repositories to a build in order to download two libraries (Google Caja and Google OAuth) which are not available in the Maven Central repository. If you were not using a repository manager, you would have added these repositories to the repository element of your project’s POM, or you would have asked all of your developers to modify ~/.m2/settings.xml to reference two new repositories. Instead, you used the Nexus repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group in Nexus, you can freely swap in new repositories without asking your developers to change local configuration, and you’ve gained a certain amount of control over which repositories are made available to your development team.

Nexus provides for anonymous access for users who only need to search repositories, browse repositories, and peruse the system feeds. This anonymous access level changes the navigation menu and some of the options available when you right-click on a repository. This read-only access displays a user interface shown in <xref linkend="fig-repoman-anonymous-interface" />.

One of the most straightforward uses of the Nexus is to browse the structure of a Maven repository. If you click on the Browse Repositories menu item in the Views menu, you should see the following display. The top-half of <xref linkend="fig-nexus-browse-repo" /> shows you a list of groups and repositories along with the type of the repository and the repository status. To browse the artifacts that are stored in a local Nexus instance, click on the Browse Storage tab for a repository as shown in <xref linkend="fig-nexus-browse-repo" />.

When you are browsing a repository, you can right click on any file and download it directly to your browser. This allows you to retrieve specific artifacts manually, or examine a <acronym>POM file in the browser.

A Nexus proxy repository acts as a local cache for a remote repository, in addition to downloading and caching artifacts locally, Nexus will also download an index of all the artifacts stored in a particular repository. When searching or browsing for artifacts, it is often more useful to search and browse the repository index. To view the repository index, click on the Browse Index tab for a particular repository to load the interface shown in <xref linkend="fig-nexus-browse-repo-index" />.

As shown in <xref linkend="fig-nexus-browse-repo-index" />, if an artifact has been downloaded from a remote repository and cached in Nexus, the artifact or folder will display a small Nexus logo.

Nexus contains ordered groups of repositories which allow you to expose a series of repositories through a single URL. More often than not, an organization is going to point Maven at the two default Nexus groups: Public Repositories and Public Snapshot Repositories. Most end-users of Nexus are not going to know what artifacts are being served from what specific repository, and they are going to want to be able to browse the Public Repository. To support this use case, Maven allows you to browse the contents of a Nexus Group as if it were a single merged repository with a tree structure. <xref linkend="fig-nexus-browse-group" />, shows the browsing storage interface for a Nexus Group. There is no difference to the user experience of browsing a Nexus Group vs. browsing a Nexus Repository.

When browsing a Nexus group’s storage, you are browsing the underlying storage for all of the repositories which are contained in a group. If a Nexus group contains proxy repositories, the Browse Storage tab will show all of the artifacts in the Nexus group that have been download from the remote repositories. To browse and search all artifacts available in a Nexus group, click on the Browse Index tab to load the interface shown in <xref linkend="fig-nexus-browse-group-index" />.

In the left-hand navigation area, there is an Artifact Search text field next to a magnifying glass. To search for an artifact by groupId or artifactId, type in some text and click the magnifying glass. Typing in the search term "guice" and clicking the magnifying glass should yield a search result similar to <xref linkend="fig-nexus-search" />.

Once you’ve located the artifact you were looking for you can click on the pom link to download the POM or the artifact link to download the artifact.

In addition to searching by a groupId or an artifactId, Nexus has a feature which allows you to search for an artifact by a checksum.

When your build makes use of proprietary or custom dependencies which are not available from public repositories, you will often need to find a way to make them available to developers in a custom Maven repository. Nexus ships with a preconfigured 3rd Party repository that was designed to hold 3rd Party dependencies which are used in your builds. To upload artifacts to a repository, select a hosted repository in the Repositories panel and then click on the Artifact Upload tab. Clicking on the Artifact Upload tab will display the tab shown in <xref linkend="fig-using-artifact-upload" />.

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters. If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it. If you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Artifact Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times.

Nexus provides feeds that capture system events, you can browse these feeds by clicking on System Feeds under the View menu. Clicking on System Feeds will show the panel in <xref linkend="fig-repoman-system-feeds" />. You can use these simple interface to browse the most recent reports of artifact deployments, cached artifacts, broken artifacts, and storage changes that have occurred in Nexus.

These feeds can come in handy if you are working at a large organization with multiple development teams deploying to the same instance of Nexus. If such an arrangement, all developers in an organization can subscribe to the RSS feeds for New Deployed Artifacts as a way to ensure that everyone is aware when a new release has been pushed to Nexus. Exposing these system events as RSS feeds also opens to the door to other, more creative uses of this information, such as connecting Nexus to external automated testing systems. To access the RSS feeds for a specific feed, select the feed in the System Feeds view panel and then click on the Subscribe button. Nexus will then load the RSS feed in your browse and you can subscribe to the feed in your favorite RSS

There are six system feeds available in the System Feeds view, and each has a URL which resembles the following URL

Where recentChanges would be replaced with the identifier of the feed you were attempting to read. Available system feeds include:

The Logs and Config Files link is only visible to Administrative users under the Views menu. Click on this option brings up the dialog shown in <xref linkend="fig-nexus-logs" />. From this screen you can view the following log and configuration files by clicking on the drop down selection next to the Download button.

If you are running Nexus Professional, you should see a few more configuration files in this directory which will correspond to the Procurement and Staging suites. The configuration files specific to Nexus Professional are:

In <xref linkend="fig-nexus-logs" /> there is a "tail" checkbox. If this box is checked, then Nexus will always show you the end of a log file. This can come in handy if you want to see a continuously updated log file. When this tail box is checked, a dropdown at the bottom of the panel allows you to set the update frequency. The contents of this dropdown are shown in <xref linkend="fig-using-update-freq" />. If an update interval is selected, Nexus will periodically refresh the selected log file.

If you have the appropriate security privilege, you will see an option to change your password in the left-hand side of the browser. To change your password, click on change password, supply your current password, and choose a new password. When you click on Change Password, your Nexus password will be changed.

If you encounter a problem with Nexus, you can use the Nexus UI to report a bug or file an issue against the Nexus project in Sonatype’s JIRA instance. To file a problem report, you will first need to sign up for an account on http://issues.sonatype.org. In Nexus 1.6, you can click on "File Issue" in the Nexus menu, supply your Sonatype JIRA credentials, and file a problem report. Supply your JIRA username and password along with a short title and a description as shown in the following figure. When you file a Nexus problem report, Nexus will create a new issue in JIRA and attach your configuration and logs to the newly filed issue.

Many of the configuration screens shown in this section are only available to administrative users. Nexus allows the admin user to customize the list of repositories, create repository groups, customize server settings, and create routes or "rules" that Maven will use to include or exclude artifacts from a repository.

In a production installation of Nexus, you’ll probably want to customize the administrative password to something other than "admin123", and you might want to override the default directories that Nexus uses to store repository data. To do this, log in as the administrative user and click on Server under Configuration in the left-hand navigation menu. The server configuration screen is shown in <xref linkend="fig-nexus-server-config" /> and <xref linkend="fig-nexus-server-config-2" />.

This screen allows you to change:

The anonymous username and password is used to integrate with other realms that may need a special username for anonymous access. In other words, the username and password here is what we attempt to authorize when someone makes an anonymous request. You would change the anonymous username to “guest” if you wanted to integrate Nexus with Microsoft’s Active Directory.

Nexus can be configured to automatically file exception and error reports with the Nexus project in the Sonatype issue tracker. Activating this setting in your own Nexus installation helps to improve Nexus as the development team will receive automatic error reports if your Nexus instance experiences an error or a failure. The Nexus Server configuration’s Automated Error Reporting Settings section is shown in <xref linkend="fig-configuring-automated-error" />. This section accepts a JIRA username and password, and allows you to configure Nexus to use the default HTTP Proxy Settings when Nexus attempts to file an error report with the Sonatype issue tracker.

To sign up for an account on the Sonatype JIRA instance, go to http://issues.sonatype.org. Once you see the website shown in <xref linkend="fig-configuring-sonatype-jira" />, click on the "Signup" link below the Login form.

Fill out the signup form shown in <xref linkend="fig-configuring-sonatype-jira-signup" />, and choose a username and password. This is the username and password you should use in the Automated Error Reporting Settings section of the Server configuration shown in <xref linkend="fig-configuring-automated-error" />.

Nexus can notify you of new versions of Nexus via the Nexus interface. To enable this feature, check the Enable checkbox in the New Version Notification section of the Nexus server settings as shown in <xref linkend="fig-configuring-new-version" />.

To manage Nexus repositories, log in as the administrative user and click on Repositories in the Views/Repositories menu in the left-hand navigation menu. If you are logged into Nexus as a user with administrative privileges, you will see Configuration and Mirrors tabs in the lower portion of the Nexus window.

Nexus provides for three different kinds of repositories:

<xref linkend="fig-repo-config" /> shows the Repository configuration screen for a Proxy repository in Nexus. From this screen, you can manage the settings for proxying an external repository. From this screen, you can configure:

If enabled, Nexus will download the index and use that for its searches as well as serve that up to any clients which ask for the index (like m2eclipse). The default for new proxy repositories is enabled, but all of the default repositories included in Nexus have this option disabled. To change this setting for one of the proxy repositories that ship with Nexus, change the option, save the repository, and then re-index the repository. Once this is done, artifact search will return every artifact available on the Maven Central repository.

Groups are a powerful feature of Nexus, they allow you to combine multiple repositories and other repository groups in a single URL. Nexus ships with two groups: public and public-snapshots. The public group combines the three hosted repositories: 3rd Party, Releases, and Snapshots with the Maven Central repository. The public-snapshots repository combines the Apache Snapshots and Codehaus Snapshots repositories.

In <xref linkend="maven-sect-single-group" /> we configured Maven via the <filename>settings.xml to look for artifacts in the public group managed by Nexus. <xref linkend="fig-group-config" /> shows the group configuration screen in Nexus, in this figure you can see the contents of the public

Note that the order of the repositories listed in Order Group Repositories is important. When Nexus searches for an artifact in a group it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the Ordered Group Repositories selection list.

The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved by Maven from a Nexus Repository Group. We recommend placing release repositories higher in the list than snapshot repositories so that LATEST and RELEASE versions are merged appropriately. We also recommend placing repositories with a higher probability of matching the majority of artifacts higher in this list. If most of your artifacts are going to be retrieved from the Maven Central Repository, putting Central higher in this list than a smaller, more focused repository is going to be better for performance as Nexus is not going to interrogate the smaller remote repository for as many missing artifacts.

Nexus Routes are like filters you can apply to Nexus Groups, they allow you to configure Nexus to include or exclude repositories from a particular artifact search when Nexus is trying to locate an artifact in a Nexus Group. There are a number of different scenarios in which you might configure a route in Nexus, the most common is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want to make sure that you are trying to retrieve your own organization’s artifacts from the hosted Release and Snapshot repositories. Nexus Routes are applicable when you are trying to resolve an artifact from a Nexus Group; using Routes allow you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.

<xref linkend="fig-route-config" /> shows the Route Configuration screen. Clicking on a route will bring up a screen which will allow you to configure the properties of a route. The configuration options available for a route are:

In this figure you can see the two dummy Routes that Nexus has as default routes.

The first route is an inclusive route, it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public Maven repositories like the Maven Central Repository or the Apache Snapshots repository.

The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains "/org/some-oss". This example might make more sense if we replaced "some-oss" with "apache" or "codehaus". If the pattern was "/org/apache", this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.

What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that Nexus Routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a Nexus Group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the Group and the repositories in the inclusive Nexus Route. The order as defined in the Nexus Group will not be affected by the Inclusive routes. Nexus will then take the result of applying the inclusive routes and apply the exclusive routes to this new group. The resulting list is then searched for a matching artifact. One straightforward use of routes is to create a route that excludes the

Maven Central repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding Central from searches for your own artifacts will reduce needless queries to the public repositories.

To summarize, there are creative possibilities with Routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping Routes. Use Routes sparingly, and use course URL patterns, as Nexus evolves there will be more features which allow for more fine grained rules to allow you to prohibit requests for specific artifacts and specific versions of artifacts. Remember that routes are only applied to Nexus Groups, routes are not used when an artifact is requested from a specific repository.

Nexus allows you to schedule tasks that will be applied to all repositories or to specific repositories on a configurable schedule. You can create the following kinds of scheduled tasks:

Minimum Snapshots to preserve in a repository - This configuration option allows you to specify a minimum number of SNAPSHOTs to preserve per artifact. For example, if you configured this option with a value of 2, Nexus will always preserve at least two SNAPSHOT artifacts.

Snapshot Retention (in days) - This configuration option allows you to specify the number of days to retain SNAPSHOT artifacts. For example, if you want to make sure that you are always keeping the last three day’s worth of SNAPSHOT artifacts, configure this option with a value of 3.

Whether snapshots should be removed if an artifact has been released - If your Nexus repository also contains a release repository, you can configure Nexus to remove all SNAPSHOT artifacts once an artifact has been released.

When you create a new service you can configure it to apply to all repositories, the repositories in a Nexus Group, or a specific Nexus Repository. A service can be scheduled to run once at a specific date and time, or periodically once every Day, Week, or Month. If none of these options suit your specific needs, you can select a recurrence of "Advanced" which will allow you to supply your own cron expression to specify when the job should execute. To create a new scheduled task, click on Scheduled Tasks under the Administration menu, and click on the Add button. This will bring up the screen shown in <xref linkend="fig-repomap-scheduled" />.

<imageobject

Nexus has role-based access control (RBAC) which gives administrators very fine-grained control over who can read from a repository (or a subset of repositories), who can administer the server, and who can deploy to repositories. The security model in Nexus is also so flexible as to allow you to specify that only certain users or roles can deploy and manage artifacts in a specific repository under a specific groupId or asset class. The default configuration of Nexus ships with four roles and four users with a standard set of permissions that will make sense for most users. As your security requirements evolve, you’ll likely need to customize security settings to create protected repositories for multiple departments, or development groups. Nexus provides a security model which can adapt to any scenario. Nexus' Role-based access control (RBAC) system is designed around the following four security concepts:

Nexus has three types of privileges: application privileges which cover actions a user can execute in Nexus, repository target privileges which govern the level of access a user has to a particular repository or repository target, and repository view privileges which control whether a user can view a repository. Behind the scenes, a privilege is related to a single REST operation and method like create, update, delete, read.

To create a new privilege, click on the Add… button in the Privileges panel and choose Repository Target privilege. Creating a privilege will load the New Repository Target Privilege form shown in <xref linkend="fig-configuring-new-privilege" />. This form takes a privilege name, a privilege description, the repository to target, and a repository target.

Once you create a new privilege, it will create four underlying privileges: create, delete, read, and update. The four privileges created by the form in <xref linkend="fig-configuring-new-privilege" /> are shown in <xref linkend="fig-configuring-new-privileges" />.

A target is a set of regular expressions to match on a path (exactly how the route rules work now). This allows you to define for example a target called Apache Maven which is "org/apache/maven/.*" You can then add a new privilege that relates to the target and controls the CRUD operations for artifacts matching that path (the privilege can span multiple repositories if you want). You could thus delegate all control of org.apache.maven targets to a "Maven" team. In this way, you don’t need to create separate repositories for each logical division of your artifacts.

Nexus ships with four roles: Nexus Administrator Role, Nexus Anonymous Role, Nexus Developer Role, and Nexus Deployment Role. Click on the Roles link under Security in the Nexus menu to show the list of roles shown in <xref linkend="fig-configuring-security-roles" />.

To create a new role, click on the Add… button and fill out the New Nexus Role form shown in <xref linkend="fig-configuring-creating-new-role" />. When creating a new role, you will need to supply a role identifier, a role name, a description, and a session timeout. Roles are comprised of other roles and individual privileges, to assign a role or privilege to a role, click on the role or privilege under Available Roles/Privileges and drag the role or privilege to the Selected Roles/Privileges list.

The built-in roles Nexus Administrator Role, Nexus Anonymous Role, Nexus Deployment Role, and Nexus Developer Role are managed by Nexus and cannot be edited or deleted. Selecting one of these built-in roles will load the form shown in <xref linkend="fig-configuring-builtin-role" />.

A Nexus role is comprised of other Nexus roles and individual Nexus privileges. To view the component parts of a Nexus Role, select the role in the Roles panel and then choose the Role Tree tab as shown in <xref linkend="fig-configuring-role-tree" />.

With the Repository Targets, you have fine grained control over every action in the system. For example you could make a target that includes everything except sources (.(?!-sources)\.) and assign that to one group while giving yet another group access to everything. This means you can host your public and private artifacts in a single repository without giving up control of your private artifacts.

Nexus ships with three users: admin, anonymous, and deployment. The admin user has all privileges, the anonymous user has read-only privileges, and the deployment user can both read and deploy to repositories. If you need to create users with a more focused set of permissions, you can click on Users under Security in the left-hand navigation menu. Once you see the list of users, you can click on a user to edit that specific user’s user ID, name, email, or status. You can also assign or revoke specific roles or permissions for a particular user.

A user can be assigned one or more roles which in turn can include references to other Nexus roles or to individual Nexus privileges. To view a tree of assigned Nexus roles and privileges, select the Role Tree for a particular user as shown in <xref linkend="fig-configuring-security-user-role-tree" />.

If you need to find out exactly how a particular user has been granted a particular privilege, you can use the Privilege Trace pane as shown in <xref linkend="fig-configuring-security-user-priv-trace" />. The Privilege Trace pane lists all of the privileges that have been granted to a particular user. Clicking on a privilege loads a tree of roles that grant that particular privilege to a user. If a user has been assigned a specific privilege by more than one Role or Privilege assignment, you will be able to see this reflected in the Role Containment list.

By default, Nexus listens on port 8081. You can change this port, by changing the value in shown in <xref linkend="ex-plexus-props" />. To change the port, stop Nexus, change the value of applicationPort in this file, and then restart Nexus. Once you do this, you should see a log you that Nexus is listening on the altered port.

You can configure the format and level of logging from within the Nexus interface. To do this, click on Log Configuration under the Administration menu in the left-hand navigation menu. Clicking on this link will display the panel shown in <xref linkend="fig-configuring-log-config" />.

From this panel you can configure the following logging configuration properties:

The other configuration parameters: Root Logger Appenders and File Append Location, are not editable in this release of Sonatype Nexus.

Use the Nexus Plugin Console to list all installed Nexus plugins and browse REST services made available by installed Nexus Plugin. To open the Nexus Plugin Console, click on the Plugin Console link in the Administration section of the Nexus menu as shown in <xref linkend="fig-configuring_plugin-console-admin-menu" />.

Once you open the Nexus Plugin Console, you will see a list of plugins installed in your Nexus installation. Clicking on a Nexus plugin in this list will display information about the plugin including: the plugin’s name, the plugin version, status, a description, SCM information about the plugin, and the URL of the plugin’s project web site.

Once you have selected a plugin from the list of installed plugin, you can browse the available REST interfaces by selecting the REST Services tab as shown in <xref linkend="fig-configuring_plugin-console-rest" />. Each plugin can contribute one or more REST services to Nexus.

Authentication realm, you will need to add the Nexus LDAP Authentication Realm to the Selected Realms in the Security section of the Server configuration panel. To load the Server configuration panel, click on the Server link under Administration in the Nexus menu. Once you have the Server configuration panel loaded, select OSS LDAP Authentication Realm in the Available Realms list under the Security section and click the Add button (or Left Arrow) as shown in <xref linkend="fig-ldap-selecting-realm" xrefstyle="select: label" />.

Next, click on the Save button in the Server configuration panel. To make sure that your Nexus instance attempts to authenticate against LDAP first, click on the OSS LDAP Authentication Realm in the Selected Realms list and drag it to the top of the list as shown in <xref linkend="fig-ldap-move-realm-to-top" xrefstyle="select: label" />. This will ensure that Nexus will consult the LDAP Server before it consults the other Authentication Realms.

To configure LDAP integration, click on the LDAP Configuration link in the Nexus menu as shown in <xref linkend="fig-ldap-config-link" xrefstyle="select: label" />. LDAP Configuration is under Security in the Nexus menu.

Clicking on the LDAP Configuration link will load the LDAP Configuration panel as shown in <xref linkend="fig-ldap-connection-authentication" xrefstyle="select: label" /> and <xref linkend="fig-ldap-user-mapping" xrefstyle="select: label" />. The following sections outline the configuration options available in the LDAP Configuration Panel.

The following figure shows Nexus configured to connect to an LDAP server running on localhost port 10389 using the search base of "ou=system". On a more standard installation, you would likely not want to use Simple Authentication as it sends the password in clear text over the network, and you would also use a search base which corresponds to your organization’s top-level domain components such as "dc=sonatype,dc=com".

<xref linkend="tbl-ldap-connection-config" xrefstyle="select: label" /> and <xref linkend="tbl-ldap-authentication-config" xrefstyle="select: label" /> contain detailed descriptions of the configuration fields in both the Connection and Authentication sections of the LDAP Configuration panel.

===User and Group Mapping

The LDAP Configuration panel also contains sections to manage User Element Mapping and Group Element Mapping as shown in <xref linkend="fig-ldap-user-mapping" xrefstyle="select: label" />.

The fields for both the User Element Mapping and Group Element Mapping sections are described in detail in <xref linkend="tbl-ldap-user-element-config" xrefstyle="select: label" /> and <xref linkend="tbl-ldap-group-element-config" xrefstyle="select: label" />.

If your installation does not use Static Groups, you can configure Nexus LDAP Integration to refer to an attribute on the User entry to derive group membership. To do this, select Dynamic Groups in the Group Type field in Group Element Mapping. Selecting Dynamic Groups will show a single field named Member of Attribute as shown in <xref linkend="fig-ldap-dynamic-groups" xrefstyle="select: label" />.

When mapping users and groups to an Active Directory installation, try the common configuration values listed in <xref linkend="tbl-ldap-ad-user-element" /> and <xref linkend="tbl-ldap-ad-group-element" />.

When mapping users and groups to LDAP entries of type posixAccount, try the common configuration values listed in <xref linkend="tbl-ldap-posix-user-element" /> and <xref linkend="tbl-ldap-posix-group-element" />.

===Mapping Roles to LDAP Users

Once User and Group Mapping has been configured, you can start verifying how LDAP users and groups are mapped to Nexus Roles. If a user is a member of an LDAP group that has a Group ID corresponding to the ID of a Nexus Role, that user is granted the appropriate permissions in Nexus. For example, if the LDAP user entry in "uid=brian,ou=users,dc=sonatype,dc=com" is a member of a groupOfUniqueNames attribute value of admin, when this user logs into Nexus, it will be granted the Nexus Administrator Role if Group Element Mapping is configured properly. To verify the User Element Mapping and Group Element Mapping, click on Check User Mapping in the LDAP Configuration panel directly below the Group Element Mapping section, <xref linkend="fig-ldap-verify-user-mapping" xrefstyle="select: label" /> shows the results of this check.

In <xref linkend="fig-ldap-verify-user-mapping" xrefstyle="select: label" />, Nexus LDAP Integration locates a user with a User ID of "brian" who is a member of the "admin" group. When brian logs in, he will have all of the rights that the admin Nexus Role has.

If you are unable to map all of the Nexus roles to LDAP groups, you can always augment the Role information by adding a specific user-role mapping for an external LDAP user in Nexus. In other words, if you need to make sure that a specific user in LDAP gets a specific Nexus role and you don’t want to model this as a group membership, you can add a role mapping for an external user in Nexus. Nexus will keep track of this association independent of your LDAP server. Nexus continues to delegate authentication to the LDAP server for this user, Nexus will continue to map the user to Nexus roles based on the group element mapping you have configured, but Nexus will also add any roles specified in the User panel. You are augmenting the role information that Nexus gathers from the group element mapping.

Once the User and Group Mapping has been configured, click on the Users link under Security in the Nexus menu. The Users tab is going to contain all of the "configured" users for this Nexus instance as shown in <xref linkend="fig-ldap-all-configured-users-initial" />. A configured user is a user in a Nexus-managed Realm or an External User which has an explicit mapping to a Nexus role. In <xref linkend="fig-ldap-all-configured-users-initial" />, you can see the three default users in the Nexus-managed default realm plus the brian user from LDAP. The brian user appears because this user has been mapped to a Nexus role.

The list of users in <xref linkend="fig-ldap-all-configured-users-initial" /> is a combination of all of the users in the Nexus default realm and all of the External Users with role mappings. To explore these two sets of users, click on the All Configured Users dropdown and choose "Default Realm Users". Once you select this, click in the search field and press Enter. Searching with a blank string in the Users panel will return all of the users of the selected type. In <xref linkend="fig-ldap-all-default-realm" /> you see a dialog containing all three default users from the Nexus default realm.

If you wanted to see a list of all LDAP users, select "LDAP" from the "All Configured Users" dropdown shown in <xref linkend="fig-ldap-all-configured-users-initial" /> and click on the search button (magnifying glass) with an empty search field. Clicking search with an empty search field will return all of the LDAP users as shown in <xref linkend="fig-ldap-all-ldap-realm" />.

To add a mapping for an external LDAP user, you would click on the "All Configured Users" dropdown and select LDAP. Once you’ve selected LDAP, type in the user ID you are searching for and click the search button (magnifying glass icon to right of the search field). In <xref linkend="fig-ldap-search-ldap-users" />, a search for "brian" yields one user from the LDAP server.

To add a Nexus role mapping for the external user "brian" shown in <xref linkend="fig-ldap-search-ldap-users" />, click on the user in the results table and drag a role from Available Roles to Selected Roles as shown in <xref linkend="fig-ldap-mapping-deploy" />. In this case, the user "brian" is mapped to the Administrative group by virtue of his membership in an "admin" group in the LDAP server. In this use case, a Nexus administrator would like to grant Brian the Deployment Role without having to create a LDAP group for this role and modifying his group memberships in LDAP

The end result of this operation is to augment the Group-Role mapping that is provided by the LDAP integration. You can use LDAP groups to manage coarse-grained permissions to grant people administrative privileges and developer roles, and if you need to perform more targeted privilege assignments in Nexus you can Map LDAP users to Nexus roles with the techniques shown in this section.

Nexus makes it very straightforward to map an external role to an internal Nexus role. This is something you would do, if you want to grant every member of an externally managed group (such as an LDAP group) a certain privilege in Nexus. For example, assume that you have a group in LDAP named "svn" and you want to make sure that everyone in the "svn" group has Nexus Administrative privileges. To do this, you would click on the Add.. dropdown in the Role panel as shown in <xref linkend="fig-ldap-select-ext-role-map" />. This dropdown can be found in the Role management panel which is opened by clicking on Roles in the Security menu.

Selecting External Role Mapping under Add… will show you a dialog which contains a dropdown of External Realms. Selecting an external realm such as LDAP will then bring up a list of roles managed by that external realm. The dialog shown in <xref linkend="fig-ldap-select-ext-role" /> shows the external realm LDAP selected and the role "svn" being selected to map to a Nexus role.

Once the external role has been selected, Nexus will create a corresponding Nexus Role. You can then assign other Roles to this new externally mapped Role. <xref linkend="fig-ldap-external-role-config" /> shows that the SVN role from LDAP is being assigned the Nexus Administrator Role. This means that any user that is authenticated against the external LDAP Realm who is a member of the svn LDAP group will be assigned a Nexus role that maps to the Nexus Administrator Role.

The following sections outline Enterprise LDAP features which are available in Nexus Professional. <section> Enterprise LDAP Failover Support When an LDAP server fails, the applications authenticating against it can also become unavailable. Because a central LDAP server is such a critical resource, many large software enterprises will install a series of primary and secondary LDAP servers to make sure that the organization can continue to operate in the case of an unforeseen failure. Nexus Professional’s Enterprise LDAP plugin now provides you with the ability to define multiple LDAP servers for authentication. To configure multiple LDAP servers, click on Enterprise LDAP under Security in the Nexus application menu. You should see the Enterprise LDAP panel shown in the following figure.

You can use the Backup Mirror setting for an LDAP repository. This backup mirror is another LDAP server which will be consulted if the original LDAP server cannot be reached. Nexus Professional assumes that the backup mirror is a carbon copy of the original LDAP server, and it will use the same user and group mapping configuration as the original LDAP server. Instead of using the backup mirror settings, you could also define multiple LDAP backup mirrors in the list of configured LDAP servers shown in the previous figure. When you configure more than one LDAP server, Nexus Professional will consult the servers in the order they are listed in this panel. If Nexus can’t authenticate against the first LDAP server, Nexus Professional will move on to the next LDAP server until it either reaches the end of the list or finds an LDAP server to authenticate against.

The feature just described is one way to increase the reliability of your Nexus instance. In the previous case, both servers would have the same user and group information. The secondary would be a mirror of the primary. But, what if you wanted to connect to two LDAP servers that contained different data? Nexus Professional also provides…

Nexus Procurement Suite provides an organization with control over what artifacts are allowed into a repository from an external, proxied repository such as the Maven Central Repository. Such control can be a prerequisite for organizations unwilling or unable to trust the entire contents of an external public repository. If an organization is developing mission critical code, they will likely want to subject every third party dependency to intense scrutiny and testing before making an artifact available to build a release or support a team of developers. In most Enterprise development environments, a developer can’t just decide to add in a new dependency to Hibernate or to the Spring Framework on a whim; the decision to add dependencies to third-party libraries will need to be funneled through an oversight process that relies on an architect or an administrator to promote artifacts to a certified release repository.

Another, more common experience is an organization which needs to proxy something like the Maven Central Repository but wants to limit access to specific versions of artifacts or prevent dependencies on everything contained under a specific group. Some organizations are more amenable to trusting the contents of a remote, proxied repository like Central, but they also need the ability to block certain dependencies. Maybe you work on a team that needs to limit access to dependencies with a certain license, or maybe you just want to make sure no one uses a problematic version of Hibernate with a known bug? The procurement suite is the tool that provides for both coarse and fine-grained control of the artifacts that can appear in a repository.

A procured repository is a Hosted Repository which procures artifacts from a Proxy Repository. For example, one could create a hosted repository named "Secured Maven Central" and then configure this hosted repository to procure artifacts from the "Maven Central" repository. Once the hosted repository has been created and the source of procurement has been configured, the repository will obtain artifacts from the proxy repository as long as procurement is activated. If you start procurement for a Hosted repository, the hosted repository will fetch artifacts from the Proxy repository specified in the procurement settings. If you stop procurement for a Hosted Repository, no additional artifacts will be retrieved from the Proxy repository specified in the procurement settings.

The ability to enable or disable procurement for a Hosted repository comes in very handy when you want to "certify" a Hosted repository as containing all of the artifacts (no more and no less) required for a production build. You can start procurement, run a build which triggers artifact procurement, and then stop procurement knowing that the procured repository now contains all of the artifacts required for building a specific project. Stopping procurement assures you that the contents of the repository will not change if the third-party, external proxied repository does. This is an extra level of assurance that your release artifacts depend on a set of artifacts under your complete control.

There are two main use cases for the Procurement Suite. In the first use case, the Procured Release Repository, the Procurement features of Nexus Professional are used to create a procured release repository to make sure that the organization has full control over the artifacts that are making it into a production release. The other use case, the Procured Development Repository, is for organizations that need more upfront control over which artifacts are allowed during the development of a project. The following sections describe these two uses cases in more detail. === Procured Release Repository

The Procurement Suite can be used in two different ways. In the "Procured Release" mode, developers work with a proxied 3rd party repository exactly as they would without the Procurement Suite. When a developer needs to add a dependency on a new artifact, Nexus will retrieve the artifact from the third-party repository (like Central or Apache Snapshots) and this artifact will be served to Maven via a proxied Nexus repository. When a QA or Release engineer needs to build a release or staging artifact, the Release or QA build would be configured to execute against a procured repository. A procured repository is one which only serves the artifacts which have been explicitly approved using the Procurement Suite.

In this model, developers can add as many third-party dependencies as they want, and it is the responsibility of the QA and Release engineers to approve (or procure) artifacts from the Development Repository to the QA/Release Repository. Developers can move forward, adding dependencies freely from a third-party, proxied repository, but once it is time to populate a Release repository, a Nexus administrator can audit the required artifacts, create a hosted repository, turn on procurement, populate the repository, and then deactivate procurement. This has the effect of "locking down" the artifacts that are involved in a production release.

There are some development environments which require even more control over which artifacts can be used and referenced by developers. In these situations, it might make sense to only allow developers to work with a procured repository. In this mode, a developer must ask a Nexus administrator for permission to add a dependency on a particular third-party artifact. A Procurement Manager would then have to approve the artifact, or group of artifacts so that they would be made available to the developers. This is the "ask-first" model for organizations that want to control which artifacts make it into the development cycle.

This is a model common in industries that have strict oversight requirements. More often than not, banks, hospitals, and government agencies have fairly strict regulations on the software that can be used by large development teams. With the Procured Development Repository approach, an architecture group can have full control over what artifacts can be referenced by a large development team.

If you installed Nexus Professional, the Nexus Procurement Suite is already installed. Just start Nexus and look for the Artifact Procurement option in the left-hand navigation menu of the Nexus interface. If you see the Artifact Procurement link as shown in <xref linkend="fig-procure-links" />, the Procurement Suite is available and ready to be configured.

This section will walk through the process of creating and configuring a hosted repository named "Procured Central" which will be procured from the "Maven Central" proxy repository. Setting up a procured repository consists of the following steps:

Before configuring a procured repository, you need to make sure that you have enabled Remote Index downloading for the proxied repository that will serve as the source for your procured repository.

When you configure procurement rules for a hosted repository, the administrative interface displays the repository as a tree of groups and artifacts populated from the Remote Repository’s Nexus Index. Nexus ships with a set of proxy repositories, but remote index downloading is disabled by default. To use procurement, you will need to tell Nexus to download the remote indexes for a proxy repository. Click on "Repositories" under Views/Repositories in the Nexus menu, then click on the Maven Central repository in the list of repositories. Click on the Configuration tab, locate Download Remote Indexes, and switch this option to "True" as shown in <xref linkend="fig-procure-enabling-remote" />.

Click on the Save button in the dialog shown in <xref linkend="fig-procure-enabling-remote" />. Right-click on the Index in the Repositories list and select "Re-Index". Nexus will then download the remote repository and recreate the index for any Repository Groups that contain this proxied repository. Nexus may take a few minutes to download the remote index for a large repository. Depending on your connection to the Internet, this process can take anywhere from under a minute to a few minutes. The size of the remote index for Maven Central is on the order of 30 MB. To check on the status of the remote index download, click on System Feeds under Views in the Nexus menu. Click on the last feed to see a list of "System Changes in Nexus". If you see a log entry like the one highlighted in <xref linkend="fig-procure-system-feed" />, Nexus has successfully downloaded the Remote Index from Maven Central.

When you configure procurement you are establishing a relationship between a Proxy repository and a Hosted repository. To create a Hosted repository, select Repositories from the Administration section of the Nexus menu, and click on the Add button selecting Hosted as shown in <xref linkend="fig-procure-add-hosted" />.

Selecting Hosted will then load the Repository Config form shown in <xref linkend="fig-procure-add-secured" />. Create a repository with a Repository ID of "secured" and a name of "Secured". Make the release policy "Release". Click the <guibutton>Save button to create the new Hosted Repository.

At this point, the list of Repositories will have a new Hosted repository named "Secured". The next step is to start procurement for the new Secured repository. When you do this, you are establishing a relationship between the new Hosted repository and a Proxy repository. In this case, we’re configuring procurement for the Secured repository and we’re telling the Procurement Suite to procure artifacts from the Maven Central proxy repository. To configure this relationship and to start procurement, click on Artifact Procurement under the Enterprise menu. In the Procurement panel, click on Add Procurement Repository as shown in <xref linkend="fig-procure-starting-procurement" />.

You will then be presented with the Start Procurement dialog as shown in <xref linkend="fig-procure-start-procurement-dialog" />. Select the "Maven Central" proxy repository from the list of available Source repositories.

.Configuring Procurement for a Hosted Repository Procurement is now configured and started, if you are using an instance of Nexus installed on localhost port 8081, you can configure your clients to reference the new Secured repository at http://localhost:8081/nexus/content/repositories/secured

By default, all artifacts are denied and without further customization of the procurement rules no artifacts will be available in the new Secured repository.

One interesting thing to note about the "Secured" repository is that the Repository Type changed, once procurement was started. When procurement is activate for a Hosted repository, the repository will show up in the Nexus interface as a Proxy repository. Click refresh in the Repositories list, and look at the Secured repository in the list of repositories, you will see that the repository type column contains "proxy" as shown in <xref linkend="fig-procure-hosted-now-proxy" />. When procurement is started for a hosted repository it is effectively a proxy repository, and when it is stopped it will revert back to being a normal hosted repository.

Once you’ve defined the relationship between a Hosted repository and a Proxy repository and you have started procurement, you can start defining the rules which will control which artifacts are allowed in a procured repository and which artifacts are denied. You can also start and stop procurement. This section details some of the administration panels and features which are available for a procured repository.

A procurement rule is a rule to allow or deny the procurement of a group, artifact, or a collection of groups or artifacts. You load the Artifact Procurement interface by selecting Artifact Procurement under the Enterprise section of the Nexus menu. Clicking on this link will load a list of procured repositories. Clicking on the repository will load the entire repository in a tree as shown in <xref linkend="fig-procure-repository-view" />. This section will illustrate the steps required for blocking access to an entire artifact and then selectively allowing access to a particular version of that same artifact. This is a common use-case in organizations which want to standardize on specific versions of a particular dependency.

The directory tree in <xref linkend="fig-procure-repository-view" /> is the index of the proxy repository from which artifacts are being procured.

To configure a procurement rule, right click on a folder in the tree. <xref linkend="fig-procure-deny-group-all" /> displays the procurement interface after right clicking on the jython artifact folder. In this dialog, we are telling the procurement interface to deny everything in the jython group and its sub-groups. If you attempt to retrieve any version under the jython artifact after this rule is created, the Procurement Suite will prevent access to this artifact. For example, if you attempt to build a project that depends on jython:jython:2.1, it will not be made available via the Secured repository created in <xref linkend="procure-sect-configure" />.

After denying access to the entire jython artifact, right-click on the 2.1 version folder under the jython artifact folder. Select "Exactly the artifact" as shown in <xref linkend="fig-procure-allowing-artifact" /> to allow for the procurement of only the 2.1 version. This has the effect of creating a specific rule which allows the procurement of a single version of the jython:jython artifact.

After allowing this element, your procurement tree is going to contain red and green markers on the affected folders as shown in <xref linkend="fig-procure-composite-effects" />. While the jython artifact folder has a red slash through it the 2.1 version folder has a green check. You have configured the Procurement Suite to deny access to all versions of the jython artifact except version 2.1.

Once you’ve created a set of procurement rules you are going to want to know how to view the procurement rules which are applicable to a particular node. Procurement rules will frequently overlap; for example, in <xref linkend="procure-sect-creating-rules" />, there are two rules: one rule applies to all of the versions (folder) below the jython artifact folder, and the other rule applies to a particular version directory. Since rules can overlap, Nexus provides a simple way to list and manage the rules which apply to a specific node in the directory tree. <xref linkend="fig-procure-composite-effects" /> shows the resolved procurement rules after clicking on the Jython 2.1 version artifact from <xref linkend="procure-sect-configure" />.

This dialog gives the procurement administrator a fine-grained view into the rules that apply to a particular node. From this dialog you can remove rules which apply to a specific node.

Some organizations may want to "lock down" the artifacts that a release build can depend upon, and it is also a good idea to make sure that your build isn’t going to be affected by changes to a repository not under you control. A procurement administrator might configure a procured repository, start procurement, and run an enterprise build against the repository to populate the procured, hosted repository with all of the necessary artifacts. After this process, the procurement administrator can stop procurement and continue to run the same release build against the hosted repository which now contains all of the procured artifacts.

To stop procurement, go to the Artifact Procurement management interface by clicking on Artifact Procurement under the Enterprise section of the Nexus menu. Right click on the repository and choose Stop Procurement as shown in <xref linkend="fig-procure-stopping" />.

After choosing Stop Procurement, you will then see a dialog confirming your decision to stop procurement as shown in <xref linkend="fig-procure-stop-confirm" />.

Once procurement is stopped, the Secure repository will revert back to being a plain-old Hosted repository. You can validate this by looking at the repository type in the list of repositories.

If you release software, you will often need to test a release before deploying it to a production system or an externally accessible repository. For example, if you are developing a large, enterprise web application you may want to stage a release candidate to a production system and perform a series of rigorous tests before a release manager makes a decision to either return a system to development or deploy a system to production.

The Nexus Staging Suite in Nexus Professional allows an organization to create a temporary staging repository and to manage the promotion of artifacts from a staging repository to a release repository. This ability to create an isolated, release candidate repository that can discarded or promoted makes it possible to support the decisions that go into certifying a release.

Without the Staging Suite, when a developer deploys an artifact to a Hosted repository such as the Release repository, this artifact is published to a hosted repository and is immediately made available - there is no oversight, there is no approval or certification process. There is no chance to test the artifact before writing the artifact to a hosted repository. If there is a mistake in the release, often the only option available is to republish the artifacts to the release repository or deploy a new version of the artifacts.

While this is acceptable for some users, organizations and enterprises with a QA cycle often need a temporary staging repository for potential release candidates: a staging repository. With the Nexus Staging Suite, an organization can automatically stage releases to a temporary repository which can then be used to test and certify a set of artifacts before they are published to a final release repository. This temporary repository can then be promoted as a whole or dropped depending on the results of testing.

Here’s how staging works in Nexus Professional:

Once the staging repository is closed, and the staging repository has been added to a Target repository group, the artifacts in the staging repository are then made available to developers or testers via a repository group. Tests can be performed on the artifacts as if they were already published in a hosted repository. From this point, one of two things can happen to a staging repository:

Nexus Professional also supports multi-level staging and build promotion. With multi-level staging, a staging repository can be tested and then promoted to a separate "build promotion" profile and exposed through different repository groups to allow for additional testing and qualification before a final release. <xref linkend="fig-staging-multi-scenario" /> illustrates a potential use for multi-level staging:

To support this multi-level staging feature, you can configure Build Promotion profiles as detailed in <xref linkend="staging-sect-config-build-profile" />. Once you have promoted a Staging Repository to a Build Promotion profile, you can drop, promote, or release the artifacts it contains as detailed in <xref linkend="sect-staging-using-build" />.

To use the Staging Suite in Nexus Professional, start Nexus and look for the Staging Profiles, Staging Repositories, Staging Rulesets, and Staging Upload options in the left-hand navigation menu of the Nexus interface. If you see the links shown in <xref linkend="fig-staging-links" />, the Staging Suite is available and ready to be configured.

Staging Profiles define the rules by which artifact deployments are staged in Staging Repositories. Staging Repositories are created as they are needed and are the primary mechanism by which Nexus users can promote or discard the contents of a staging repository to a hosted repository. A staging profile uses a Repository Target to match artifacts as they are deployed. If a matching artifact is deployed to Nexus, the Staging Suite will intercept this deployment and store the artifact in a staging repository.

The process for configuring a new Staging Profile is as follows:

The following sections provide a more detailed look at the process of configuring a single staging profile in Nexus Professional.

The Staging Suite intercepts deployments to repository targets. For example, if you wanted to intercept all deployments to the com.sonatype.sample groupId, you would create a Repository Target called the "Sample Target" with a pattern expression of "<varname>./com/sonatype/sample/.". Do this by clicking on "Repository Targets" in the left-hand navigation menu in Nexus and then clicking on the <guibutton>Add

Staging profiles control the process by which artifacts are selected for staging. When you define a Staging profile, you are defining a set of rules which will control the way in which Nexus intercepts an artifact deployment. When you click on Staging Profiles in the Nexus menu, you will see a list of configured staging profiles. Clicking on Add… will display the dropdown menu shown in <xref linkend="fig-staging-add-staging-profile" />.

Selecting Staging Profile will create a new Staging Profile and display the form shown in <xref linkend="fig-staging-edit-profile" />.

<xref linkend="fig-staging-edit-profile" /> defines a Staging Profile using the Repository Target configured in <xref linkend="staging-sect-define-target" />. This target will match all artifacts under the <varname>com.sonatype.sample groupId (or the <filename>com/sonatype/sample repository path). This staging profile uses the "Maven2 (hosted, release)" as a template for newly created temporary staging repositories, and it will automatically add closed staging repositories to the Public Repositories group.

This form allows you to configure a profile. Every profile has a name, is associated with a Repository Target, and points to a template to use when creating a new staging repository. The Staging Profile configuration panel contains the following fields:

Once you’ve created a Staging Repository with the values shown in <xref linkend="fig-staging-edit-profile" />, you are ready to perform a test deployment to the Staging URL.

A Build Promotion profile is used when you need to add an additional step between initial staging and final release. To add a new Build Promotion profile, open the Staging Profiles link from the Nexus menu and click on Add… to display the dropdown menu shown in <xref linkend="fig-staging-build-promo-link" />. Select Build Promotion Profile from this dropdown to create a new Build Promotion Profile.

After creating a new Build Promotion profile, you will see the form shown in <xref linkend="fig-staging-build-promo-profile" />. This form contains the following configuration fields:

To perform a staged deployment, the user deploying the artifact must have the "Staging: Deployer (admin)" role or the "Staging: Deployer" role for a specific Staging Profile.

When you create a Staging Profile, Nexus will create two new Nexus roles that grant permissions specific to that staging profile. If you created the Staging profile from the previous section, Nexus would have created two roles:

In addition to the profile-specific staging roles, the Staging Suite also defines two universal roles which grant read-only or deployer rights across all staging repositories. These roles are:

To configure the deployment user with the appropriate staging role, click on Users under the Security menu in the Nexus menu. Once you see the Users panel, click on the deployment user to edit this user’s roles. If the Staging Suite is installed, you should see the "Staging: Deployer (admin)" role listed in Available Roles. Select the "Staging: Deployer (admin)" role and then click the left arrow to add this role to the deployment user’s list of assigned roles.

Once the deployment user has the "Staging: Deployer (admin)" role, you can then use this user to deploy to the staging URL and trigger any Staging Profile. Without this permission, the deployment user would not be able to publish a staged artifact. If you need to add a specific permission to activate a single Staging Profile, you would select that specific role in the Available Roles list shown in <xref linkend="fig-staging-assigning-role" />. In this figure, note that there are two "Staging: Deployer" roles: one for general administrative permission to deploy to any staging profile, and another which targets a specific staging profile.

In the previous section, you created a Staging Profile which references the Repository Target created in <xref linkend="staging-sect-define-target" />. If the Staging Suite is configured correctly, any deployment to the staging URL under the groupId com.sonatype.sample should be intercepted by the Staging Suite and placed in a temporary staging repository. Once this repository has been closed, it will be made available in the Target Group you selected when you configured the Staging Profile in <xref linkend="staging-sect-config-profile" />.

In this section, you will create a new project using the Maven Archetype plugin to test the Staging Profile you created in the previous section.

To create a new project run <command>mvn archetype:generate. Running this at the command line will bring up a list of archetypes, choose the default maven-archetype-quickstart or number 16, and use the identifier values listed in <xref linkend="tbl-staging-new-project" /> for the new project.

If the archetype generate goal is executed successfully, you should have output which resembles the following screen listing:

To deploy a staged released, a developer needs to deploy to the staging URL. To configure this new project to deploy to the Staging URL, add the a <sgmltag>distributionManagement element to the stage-test project’s POM.

This configuration element, distributionManagement, defines the repository to which our deployment will be made. It references the Staging Suite’s Staging URL: http://localhost:8081/nexus/service/local/staging/deploy/maven2

This URL acts as a something of a virtual repository to be published to. If an artifact being published matches one of the Repository Targets in a Staging Profile, that Staging Profile is "activated" and a temporary Staging Repository is created for a specific client as defined by the combination of a client’s IP address, Deployment User name, and User-Agent.

To successfully deploy to your Nexus instance, you will need to update your Maven Settings with the credentials for the deployment user. These credentials are stored in the Maven Settings file in _{/.m2/settings.xml. To add these credentials, add the following element to the servers element in your} /.m2/settings.xml file as shown in <xref linkend="ex-staging-deployment-credentials" />.

Note that the server identifier listed in <xref linkend="ex-staging-deployment-credentials" /> matches the server identifier listed in <xref linkend="ex-staging-dist-management" />. The deployment credential listed in <xref linkend="ex-staging-deployment-credentials" /> contains the default password for the Nexus deployment user - deployment123. You should change this password to match the deployment password for your Nexus installation.

Once the sample project’s <sgmltag>distributionManagement has been set to point at the Nexus Staging URL and your deployment credentials are updated in your ~/.m2/settings.xml file, you can deploy to the Staging URL. To do this, run <command>mvn deploy

You can also upload a staged deployment via the Nexus interface. To upload a staged deployment, select Staging Upload from the Nexus menu. Clicking Staging Upload will show the panel shown in <xref linkend="fig-staging-artifact-upload" />.

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters.

If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it, but if you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file which was associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Staging Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times. This interface also accepts an Artifact Bundle which is a JAR that contains more than one artifact.

Once a staging artifact upload has been completely configured, click on Upload Artifact(s) button to begin the upload process. Nexus will upload the artifacts to the Staging URL which will trigger any staging profiles that are activated by the upload. If a staging profile is activated, a new staging repository will be created and can be managed using the procedures outlined in <xref linkend="staging-sect-managing-staging" />.

Nexus Professional has the ability to define staging rules that must be satisfied before a staging repository can be promoted.

Staging Rulesets are groups of rules that are applied to a Staging repository at promotion time. A staging repository associated with a staging ruleset cannot be promoted until all of the rules associated with the rulesets have been satisfied. This feature allows you to set standards for your own hosted repositories, and it is the mechanism that is used to guarantee the consistency of artifacts stored in the Maven Central repository.

Nexus Professional contains the following rules:

If any of these POM elements are missing or empty, this Staging Ruleset will cause a promotion to fail.

To create a Staging Ruleset, click on the Staging Ruleset link in the Nexus Menu. This will load the interface shown in <xref linkend="fig-staging-rulesets" />. The Staging Ruleset panel is used to define sets of rules that can be applied to Staging Profiles. <xref linkend="fig-staging-rulesets" /> shows a ruleset which contains all four predefined staging rules.

To define a ruleset to be used for promotion, click on Staging in the Nexus menu and select a Staging Profile. Click on the Configuration tab, and scroll down to the Promote Repository Staging Rulesets section of the Staging Profile configuration as shown in <xref linkend="fig-staging-associate-ruleset" />. The next time you attempt to promote a staging repository that was created with this profile, Nexus Professional will check that all of the rules in the associated rulesets are being adhered to.

Once you complete the process outlined in <xref linkend="staging-sect-deployment" />, you will then have an automatically generated Staging Repository. In this section, you will walk through the process of managing staging repositories. Once a staging repository has been created, there are two steps in the lifecycle of a staging repository. Once you have deployed a set of related artifacts, you must "Close" the repository moving it from an "Open" to a "Closed" state. Once a repository is in the "Closed" state it is added to a Repository Group and is made available for testing purposes. Once testing is completed, a Nexus administrator can either Promote or Drop a Closed repository. If the repository is Dropped, the repository is discarded and removed from the Repository Group. If the repository is Promoted, the Nexus administrator can select a Hosted repository and publish the contents of the temporary staging repository to a Hosted repository.

Once you deploy an artifact that triggers a staging profile, Nexus Staging Suite will create a repository that contains the artifacts you deployed. A separate staging repository is created for every combination of User ID, IP Address, and User Agent. This means that you can perform more than one deployment to a single Staging Repository as long as you perform the deployment from the same IP, with the same deployment user, and the same installation of Maven. You can perform multiple deployments to an "Open" staging repository, to see a list of these temporary "Open" Staging repositories, select "Staging" from the Nexus menu and click on the appropriate Staging Profile to browse a list of staging repositories which correspond to a staging profile.

Once you are ready to start testing the staging repository, you will need to transition the staging repository from the "Open" state to the "Closed" state. This will close the temporary staging repository to more deployments. To close a repository, right-click on the repository in the Staging Repositories panel and select "Close". This will bring up the following dialog for a staging deployer to describe the contents of a staging repository. This description field can be used to pass essential information to the person that needs to test a deployment. In <xref linkend="fig-staging-close-description" />, the description field is used to describe the release for the user that needs to certify and promote a release.

Confirming this state transition will close the repository and add the repository to a repository group. Once a repository has been closed, it will be listed as "Closed" in the Profile’s Repositories tab.

Once the Staging Repository has been closed, it will automatically be added to the Repository Group that was specified in the Staging Profile. <xref linkend="fig-staging-add-to-group" /> shows an instance of a staging repository appended to the end of a group named "Public Repositories". This has the effect of making the staged artifacts available to everyone who is referencing this public group. Developers who are referencing this public repository group can now test and interact with the staged artifacts as if they were published to a Hosted repository. While the artifacts are made available in a repository group, the fact that they are held in a temporary staging directory gives the administrator the option of promoting this set of artifacts to a Hosted repository or dropping this temporary staging repository if there are problems discovered during the testing and certification process for a release.

Once a staging repository is closed, you can also browse and search the repository. To view Staging Repositories, click on Browse Repositories and then select Nexus Managed Repositories as shown in <xref linkend="fig-staging-selecting-nexus" />.

Once you’ve selected Nexus Managed Repositories, Nexus will then show you all of the repositories that have been created by the Nexus Staging Suite. You can select and browse this temporary Staging Repository as you would any other repository.

You can browse the contents of a staging repository from the Staging Repositories panel. Click on Staging Repositories in the Nexus menu, click on a Staging Repository to browse the contents and perform operations a staging repository.

Once you are finished testing or certifying that the contents of a Staging Repository are correct, you are ready to either Release or Drop the Staging Repository. Dropping the Staging Repository will delete the temporary staging repository from Nexus and remove any reference to this repository from the groups it was associated with. Releasing the Staging Repository allows you to publish the contents of this temporary repository to a Hosted repository.

To release a Staging Repository select Staging from the Nexus menu and then click on the appropriate Staging Profile. This will display a list of Staging Repositories associated with that Staging Profile. To release the contents of a repository, load the list of Staging Repositories, check the box next to the staging repository you which to promote and then click the Release button shown in <xref linkend="fig-staging-promote" />.

Once you click Release, the Nexus Staging Suite will ask you to supply a description for this release action.

Supplying a description and clicking on Release will publish the contents of a Staging Repository to a Hosted repository and delete the Staging Repository from Nexus.

If you have a staging repository that you want to promote to a Build Promotion profile, open the list of Staging Repositories by selecting Staging Repositories from the Nexus menu, select the repository you intend to promote, and click the Promote button as shown in <xref linkend="fig-staging-promote-button" />.

After clicking the Promote button the Promote Staging Repository shown in <xref linkend="fig-staging-promote-stating" /> will be displayed. In this dialog, you can choose the Build Promotion profile to promote the staging repository to, and you can supply a short description of the promotion. Clicking on the Promote button in this dialog will promote the staging profile to a build promotion profile and expose the contents of the selected staging repository through a group associated with the build promotion profile.

After you promote a staging repository to a Build Promotion profile the build promotion profile will create a temporary repository which contains the contents of the promoted staging repository. The staging repository will be a Group Member of the Build Promotion repository. One or more staging repositories can be promoted to a single Build Promotion profile, and you can browse the Group Member by selecting the Build Promotion repository and viewing the Group Member tab as shown in <xref linkend="fig-staging-group-members" />.

When you configure a Build Promotion profile and promote Staging Repositories to promotion profiles, each Build Promotion profile creates a repository which contains one or more Staging Repositories. Just like you can promote the contents of a Staging Repository to a Build Promotion profile, you can also promote the contents of a Build Promotion profile to another Build Promotion profile. When you do this you can create hierarchies of staging repositories and build promotion profiles which can then be dropped or released together.

When you promote a staging repository to a build promotion profile, you make the contents of a staging repository available via a repository group associated with a build promotion profile. For example, if you staged a few artifacts to a QA Staging Repository and then subsequently promoted that repository to a Closed Beta Build Promotion group, the contents of the QA Staging Repository would initially be made available via a QA Repository Group. After a build promotion, these artifacts would also be available via a Closed Beta repository group. You can take it one step further and promote the contents of the Closed Beta Build Promotion profile to yet another Build Promotion profile. In this way you can have an arbitrary number of intermediate steps between the initial staging deployment and the final release.

If you drop the contents of a build promotion profile, you roll back to the previous state. For example, if you decided to drop the contents of the Closed Beta build promotion group, Nexus will revert the status of the Staging Repository from promoted to closed, and make the artifacts available via the QA Staging Repository. The effects of promoting, dropping, and releasing artifacts through a series of Staging Profiles and Build Promotion Profiles is shown in <xref linkend="fig-staging-build-promo-agg" />.

When you perform a release on a Build Promotion profile, each Staging Repository is going to release artifacts to the Release Repository configured in <xref linkend="fig-staging-edit-profile" />. Because a Build Repository can contain one or more promoted staging repositories, this means that releasing a Build Promotion profile can cause artifacts to be published to more than one Release Repository. Build Promotion profiles are not directly related to release repositories, only staging profiles are directly associated with target release repositories. <xref linkend="fig-staging-multi-to-one" /> illustrates this behavior with two independent Staging Repositories each configured with a separate Release Repository. Releasing the Build Promotion profile causes Nexus to publish each Staging Repository to a separate hosted repository.

You can do everything that was described in <xref linkend="staging-sect-managing-staging" /> with the Nexus Maven Plugin. Using the Nexus Maven Plugin you can:

To invoke goals in the Nexus Maven plugin, you will want to add the appropriate plugin group to your Maven settings file. Add the org.sonatype.plugins groupId to <filename>~/.m2/settings.xml as shown in <xref linkend="ex-staging-nexus-plugin-group" />.

Adding the <varname>org.sonatype.plugins group to your Maven Settings will allow you to run the following goals from the Nexus Maven Plugin:

Once you have configured the <sgmltag>pluginGroup in your Maven Settings file, you can run the Nexus Maven plugin from the command line. In order to access the staging suite in your Nexus instance, the plugin must be told where Nexus is.

All of the Staging goals in the Nexus Maven plugin require security credentials and a base URL for the Nexus server you are attempting to manage. You can specify security credentials by supplying a username and password or by supplying a server id that corresponds to a server in your Maven Settings (~/.m2/settings.xml). The common configuration parameters and security configuration properties are:

In most cases a valid user login will be required to access your staging information. By default, if you don’t specify the nexusUrl and password parameters, the plugin will prompt you for them. If you don’t specify the username parameter, the Java System property <varname>\${user.name}

In addition to these security options, all of the staging goals have a common configuration property which controls the logging level.